[Feature]

In raising this pull request, I confirm the following (please check boxes):

• I have read and understood the contributors guide.
• I have checked that another pull request for this purpose does not exist.
• I have considered, and confirmed that this submission will be valuable to others.
• I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
• I give this submission freely, and claim no ownership to its content.

My familiarity with the project is as follows (check one):

• I have never used the project.
• I have used the project briefly.
• I have used the project extensively, but have not contributed previously.
• I am an active contributor to the project.

Overview

First PR of a 7-part stack that adds a token-authenticated JSON REST API (/api/v1) to the sample platform, giving CI consumers and future tooling programmatic access to runs, samples, results, and logs — everything that today requires scraping the HTML views.

Stack: #1130 → #1131 → #1132 → #1133 → #1134 → #1135 → #1141. Merge bottom-up. Each PR contains the ones below it, so the diff shrinks automatically as parents merge.

This PR deliberately contains no endpoints. It lays down the infrastructure the six route PRs build on, so their reviews can focus on endpoint logic.

What's in it

Blueprint + middleware (mod_api/)

• mod_api blueprint registered at /api/v1. Anything under that prefix returns structured JSON errors ({code, message, details}) — including routing-level 404/405s, which are converted app-wide via an after_app_request hook so no HTML error page ever leaks into an API response.
• Bearer auth: Authorization: Bearer spci_... (scheme matched case-insensitively per RFC 7235). Tokens are 256-bit random secrets; the server stores only a SHA-256 hash plus an indexed 16-char prefix for lookup. Verification fetches candidates by prefix and compares hashes with hmac.compare_digest (constant-time). Scope checks (@require_scope) and role checks (@require_roles) are separate decorators, so each endpoint's requirements are visible at its definition.
• Rate limiting: per-client sliding window with standard X-RateLimit-* response headers. In-memory by design — single-process deployment; the store interface is small enough to swap for Redis if that ever changes.
• Security headers on every API response; hook registration order (and Flask's reverse execution order for after_request) is documented in mod_api/__init__.py.
• Validation helpers: offset/cursor pagination, path-id, date-range, and sort-parameter validators used consistently by all later PRs.

Model + migration

• ApiToken model: name (unique per user, kept after revocation for audit), hash, prefix, JSON scopes, expiry, revocation timestamps.
• Alembic migration d4f8e2a1b3c7: new api_token table + nullable user.github_login column. Purely additive — no existing table is modified, so it's safe for the deployment pipeline to auto-apply, and rolling back the code without rolling back the schema is harmless.

Status derivation service (mod_api/services/status.py)
The single source of truth mapping raw TestProgress/TestResult/TestResultFile rows to normalized statuses (runs: queued/running/pass/fail/canceled/error/incomplete; samples: pass/fail/skipped/missing_output/running/not_started). Route handlers are forbidden from inlining their own derivation — this is what keeps /summary, /samples, and /errors from ever disagreeing. Documented data-model traps it encodes: TestResultFile.got = NULL means match, not missing; the (-1, 'error') dummy row means the test produced no output; test.failed only reflects cancellation. A run marked completed that produced zero result rows reports error, never pass.

Test scaffolding
tests/api/base.py provides ApiTestCase, which stubs the deliberately-slow sha512_crypt password hashing for API tests (they create users/tokens constantly). This keeps the API suite in the seconds range instead of minutes; any test needing real hashing can stop the patchers locally.

Testing

42 tests: token model (generation, hashing, prefix extraction, expiry), status derivation (including the completed-without-results → error case), validation helpers, and utils. Full lint battery (isort, pycodestyle, pydocstyle, dodgy, mypy) is green.